[<<Previous Entry]
[^^Up^^]
[Next Entry>>]
[Menu]
[About The Guide]
THE NANFORUM TOOLKIT (NANFOR.LIB)
PUBLIC DOMAIN USER SUPPORTED CLIPPER FUNCTION LIBRARY
(part 2)
5 FUNCTION CODING STANDARDS
The goal of this standard is not to force anyone to rewrite his
code for this library, but to create some consistency among the
functions so that they may more easily maintained and understood
by all CA-Clipper developers, both novice and advanced.
However, it is extremely important that anyone submitting code
attach the proper headers and documentation and fill them out
correctly. This will make it much easier for code to be added to
the library.
5.1 Required sections for each function
5.1.1 Header (author name/etc, version ctrl info)
Figure 1 shows a header that must be included at
the top of every piece of source code submitted to
the library. This header will work with both CA-
Clipper and C code. For ASM code, substitute each
asterisk ("*") with a semicolon (";") and delete
the slashes ("/").
/*
* File......:
* Author....:
* CIS ID....: x, x
* Date......: $Date$
* Revision..: $Revision$
* Log file..: $Logfile$
*
*
* Modification history:
* ---------------------
*
* $Log$
*
*/
Figure 1 - Standard function header.
Note that the date, revision, logfile, and
modification history fields will be maintained by
the librarian and should not be edited or adjusted
by code authors.
The "File" field shall contain the source file
name. This is often independent of the individual
function name. For example, a function named
ft_screen() would be included in SCREEN.PRG. As a
rule, source files (.PRG, .C, .ASM) should not
have the "FT" prefix.
The "Author" field should have the author's full
name, and CIS number. A CIS number is important,
as this will make bug fixing and other
correspondence easier.
5.1.2 Public domain disclaimer
Authors shall simply state "This is an original
work by [Author's name] and is hereby placed in
the public domain."
5.1.3 Documentation block
/* $DOC$
* $FUNCNAME$
*
* $ONELINER$
*
* $SYNTAX$
*
* $ARGUMENTS$
*
* $RETURNS$
*
* $DESCRIPTION$
*
* $EXAMPLES$
*
* $SEEALSO$
*
* $INCLUDE$
*
* $END$
*/
Figure 2 - Standard Documentation Header
The documentation block must be carefully
formatted as it is used by the documenter to
produce the Norton Guide documentation for the
library.
The keywords enclosed in dollar-signs delimit
sections of the documentation header analogous to
those in the CA-Clipper 5.0 documentation.
Documentation should be written in the same style
and flavor as the CA material, if possible. Refer
to the CA-Clipper documentation for more detail
and numerous examples.
The documentation will appear on comment lines
between the keywords. Examples are optional. Do
not put documentation on the same line as the
comment keyword.
Note that the $DOC$ and $END$ keywords serve as
delimiters. Do not place any text between $DOC$
and $FUNCNAME$, or any documentation after the
$END$ keyword, unless that documentation belongs
in the source code file and not in the resultant
Norton Guide file.
The $FUNCNAME$ keyword should be followed by the
function name, with parentheses, and no arguments
or syntax, such as:
$FUNCNAME$
ft_screen()
Note the indent for readability. Parentheses
shall be added after the function name as shown
above.
The $ONELINER$ keyword should be followed by a
simple statement expressing what the function
does, phrased in the form of a command, e.g.:
$ONELINER$
Sum the values in an array
The length of the entire $ONELINER$ shall not
exceed 60 characters (this is a Norton Guide
limitation).
The $SYNTAX$ keyword should be followed by a CA-
standard syntax specifier, such as:
$SYNTAX$
ft_screen( <nTop> [,<nBottom>] ) -> NIL
All parameters have proper prefixes (see paragraph
5.4), and are enclosed in <angle brackets>.
Optional parameters are enclosed in [square
brackets] as well. An arrow should follow,
pointing to the return value. If there is no
return value, it should be NIL. Any others should
be preceded with the proper prefix (see the CA-
Clipper documentation).
The $SEEALSO$ field provides a way to generate
cross-references in the Norton Guide help
documentation. Use it to point the user to other
related functions in the forum toolkit. For
example, if ft_func1() is also related to
ft_func2() and ft_func3(), the field would look
like this:
$SEEALSO$
ft_func2() ft_func3()
Note that fields are separated by spaces and the
parentheses are included.
The $INCLUDE$ area allows you to specify what
files are included by this function (this will be
used to organize the on-line help file, and
possibly the master makefile). An example would
be
$INCLUDE$
int86.ch int86.inc
Other documentation fields should be self-
explanatory. Review the appendix for a sample.
All fields are required and must be filled in.
Examples should not be considered optional.
5.1.4 Sample header and documentation block
Refer to the Appendix for a sample header and
documentation block.
5.1.5 Test driver
A test driver is an optional section of C or CA-
Clipper code that will only be compiled under
certain circumstances. Developers are encouraged
to include a short "test section" in front of
their code.
The test driver shall be surrounded by the
following pre-processor directives, and placed at
the top of the source file:
#ifdef FT_TEST
[test code]
#endif
The test driver is currently optional, but authors
submitting CA-Clipper code should seriously
consider adding it. It is a good way to include
short demos within a piece of source code, yet pay
no penalty because it is only compiled if needed.
It will be invoked when a #define is created that
says "#define FT_TEST." This is a way for
submitters to include short test routines with
their functions and yet keep it all in one source
file. This will be useful to end users.
This test driver may become required in a future
version of the RFC.
5.1.6 Code
The source code shall be formatted as described in
paragraph 5.4.
5.2 Function names
All NANFOR.LIB functions start with one of two prefixes. If
the function is to be called by user programs, then it will
begin with the prefix
FT_ ("F", "T", underscore)
Note that "FT" is a mnemonic for "Forum Toolkit." If the
function is "internal" to a module, then it will be prefixed
by an underscore:
_FT ( Underscore, "F", "T" )
with no trailing underscore. Examples:
FT_CURDIR() "external"
_ftAlloc() "internal"
5.3 Librarian's authority to change function names
Some functions will be submitted that either (1) bear a
similar name to another function in the library, or (2) bear
an inappropriate name. For example, a function called
FT_PRINT that writes a character to the screen could be said
to be named inappropriately, as a name like FT_PRINT implies
some relationship to a printer. The librarian shall have
the responsibility to rename submitted functions for clarity
and uniqueness.
5.3.1 Changing a function name after it has been
released
Once the library is released with a particular
function included, then a function name should
generally be frozen and not renamed. To do so
would probably cause difficulties with users who
had used the previous name and are not tracking
the changes to the library.
5.4 Source code formatting
5.4.1 CA-Clipper
CA-Clipper code shall be formatted in accordance
with CA's currently defined publishing standard.
Although there will surely be some debate over
whether this is a good idea, in general, the goal
is to provide something consistent that all CA-
Clipper developers will recognize.
Minor deviations will be permitted.
The CA standard usually means uppercase keywords,
and manifest constants, and lower case everything
else.
In addition, identifiers shall be preceded with
the proper metasymbol:
n Numeric
c Character or string
a Array
l Logical, or boolean
d Date
m Memo
o Object
b Code block
h Handle
x Ambiguous type
Refer to the CA-Clipper documentation for samples
of CA's code publishing format.
5.4.2 C
C source code shall be formatted in a generally
accepted way, such as Kernighan and Ritchie's
style used in the book _The C Programming
Language_." The use of CA's EXTEND.H is
encouraged.
5.4.3 ASM
No particular formatting conventions are required
for assembly language source code, since assembly
code formatting is fairly standard. Lowercase
code is preferred. Be sure to include the proper
documentation header information, as described
above.
Do not place ASM code in DGROUP. See paragraph
5.11.
5.5 Organization into .PRGs
Since many different people will be submitting routines, it
is probably best if all routines that belong together are
housed in the same .PRG. If there is some reason to split
the .PRG, the referees and the librarian will handle that as
part of library organization.
5.6 Header files
Including a ".ch" or ".h" or ".inc" file with each function
would get unwieldy. For the purpose of NANFOR.LIB, all
#defines, #ifdefs, #commands, #translates, etc that belong
to a particular source file shall be included at the top of
that source file. Since few submissions will split over
multiple source files, there will usually be no need to
#include a header in more than one place.
If a "ch" file will make the end user's job of supplying
parameters and other information to NANFOR.LIB functions
easier, then it shall be submitted as a separate entity.
The referees will decide on whether to include these
directives in a master NANFOR.CH file.
5.7 CA-Clipper 5.0 Lexical Scoping
NANFOR.LIB routines that are written in CA-Clipper will make
use of CA-Clipper 5.0's lexical scoping features to insulate
themselves from the rest of the user's application.
For example, all "privates" shall generally be declared
"local."
If a package of CA-Clipper functions is added to the
library, then the lower-level, support functions will be
declared STATIC as necessary.
5.8 Use of Publics
Authors shall not use PUBLIC variables in NANFOR.LIB
functions, due to the potential interference with an
end-user's application or vice versa.
If a global is required for a particular function or package
of functions, that global shall be accessed through a
function call interface defined by the author (.e.g,
"ft_setglobal()", "ft_getglobal()", and so on). Globals
such as these shall be declared static in the .PRG that
needs them.
5.9 Use of Macros ("&" operator)
The use of macros in NANFOR.LIB functions will be, for the
most part, unnecessary. Since this is a CA-Clipper 5.0
library, the new 5.0 codeblock construct should be used
instead. Anyone having trouble figuring out how to convert
a macro to a codeblock should post suitable questions on the
CLIPPER forum on CompuServe.
5.10 Use of Static Functions
Any CA-Clipper 5.0 function that is only needed within the
scope of one source file shall be declared STATIC. This
applies mostly to NANFOR.LIB "internals" (names with an
"_ft" prefix) that user programs need not access.
5.11 Use of DGROUP in ASM Functions
Use of DGROUP in assembly language functions shall be
avoided, in accordance with CA's recommendations. Assembly
functions written for NANFOR.LIB shall use a segment named
_NanFor, as in the following example:
Public FT_ChDir
Extrn _ftDir:Far
Segment _NanFor Word Public "CODE"
Assume CS:_NanFor
Proc FT_ChDir Far
.
.
.
Ret
Endp FT_ChDir
Ends _NanFor
End
5.12 Use of "Internals"
Use of CA-Clipper "internals" by code authors is
allowed. However, should any code make use of an
internal, i.e., a function or variable that is not part
of the published CA-Clipper API, then that internal
shall be clearly marked in the documentation (under
"DESCRIPTION") and in the actual code, everywhere the
internal is used.
5.13 Procedures for compiling functions
5.13.1 CA-Clipper
CA-Clipper functions will be compiled under the
current release of CA-Clipper 5.0, with the
following compiler options:
/n /w /l /r
Note that neither line numbers nor debugging
information will find its way into NANFOR.LIB, to
keep the code size down. End users may recompile
NANFOR.LIB with these options enabled if they want
to view NANFOR.LIB source in the debugger.
5.13.2 ASM
Assembly functions must compile successfully
under any MSDOS assembler capable of producing the
proper .OBJ file. However, care should be taken
not to use any macros or special syntax particular
to one vendor's assembler, because that would make
it difficult for end users to recompile the
source. The preferred assembler is MASM, followed
by TASM.
5.13.3 C
C functions must compile successfully under any C
compiler capable of interfacing to CA-Clipper.
Obviously, Microsoft C, version 5.1, is the
preferred development environment. Care should be
taken, when writing C code, not to use any special
compiler features particular to one vendor's C
compiler, because that would make it difficult for
end users to recompile the source.
5.14 Functions requiring other libraries
It is very easy to write functions in C that call the
compiler's standard C library functions. However,
NANFOR.LIB can make no assumptions about the end user's
ability to link in the standard library or any other
library. Therefore, no function will be added to
NANFOR.LIB that requires any other third party or compiler
manufacturer's library.
6 ADMINISTRATIVE DETAILS
6.1 Librarian
The librarian will be the person who rebuilds the library
from the sources and uploads the resulting deliverables to
the proper CLIPPER forum library on CompuServe. The
librarian generally does *not* test code or edit source code
to repair formatting errors.
6.2 Documenter
The documenter is responsible for maintaining the Norton
and guides and keeping it in sync with each new release.
6.3 Referees
Referees are volunteers who read source code, clean it up,
compile it, look for problems like potentially problematic C
code, decide on which function is best, consolidate common
functions, etc. They make sure the header and documentation
blocks are present. There is no election or term for
refereedom. One simply performs the task as long as one can
and bows out when necessary.
6.4 Transitions
Not everyone will be able to stay around forever to keep
working on this project. Therefore, it is the
responsibility of each referee, documenter, or librarian to
announce as far in advance as possible his or her intention
to leave, in order to give everyone a chance to come up with
a suitable replacement. Don't let it die!
7 CONTRIBUTORS
Current contributors, directly and indirectly, to this
document include:
Don Caton [71067,1350]
Bill Christison [72247,3642]
Robert DiFalco [71610,1705]
Paul Ferrara [76702,556]
David Husnian [76064,1535]
Ted Means [73067,3332]
Steve Kolterman [76320,37]
Alexander Santic [71327,2436]
Glenn Scott [71620,1521]
Keith Wire [73760,2427]
Craig Yellick [76247,541]
James Zack [75410,1567]
See Also:
Overview, Part 1
This page created by ng2html v1.05, the Norton guide to HTML conversion utility.
Written by Dave Pearson